home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / tcl / tcl67.lha / tcl6.7 / doc / library.n < prev    next >
Text File  |  1993-01-31  |  9KB  |  229 lines
  1. '\"
  2. '\" Copyright 1991-1992 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/library.n,v 1.8 93/01/31 15:35:47 ouster Exp $ SPRITE (Berkeley)
  11. '
  12. .so man.macros
  13. .de UL
  14. \\$1\l'|0\(ul'\\$2
  15. ..
  16. .HS library tcl
  17. .BS
  18. .SH NAME
  19. library \- standard library of Tcl procedures
  20. .SH SYNOPSIS
  21. .nf
  22. \fBauto_execok \fIcmd\fR
  23. \fBauto_load \fIcmd\fR
  24. \fBauto_mkindex \fIdir pattern\fR
  25. \fBauto_reset\fR
  26. \fBparray \fIarrayName\fR
  27. \fBunknown \fIcmd \fR?\fIarg arg ...\fR?
  28. .fi
  29. .BE
  30.  
  31. .SH INTRODUCTION
  32. .PP
  33. Tcl includes a library of Tcl procedures for commonly-needed functions.
  34. The procedures defined in the Tcl library are generic ones suitable
  35. for use by many different applications.
  36. The location of the Tcl library is returned by the \fBinfo library\fR
  37. command.
  38. In addition to the Tcl library, each application will normally have
  39. its own library of support procedures as well;  the location of this
  40. .VS
  41. library is normally given by the value of the \fB$\fIapp\fB_library\fR
  42. global variable, where \fIapp\fR is the name of the application.
  43. For example, the location of the Tk library is kept in the variable
  44. \fB$tk_library\fR.
  45. .VE
  46. .PP
  47. To access the procedures in the Tcl library, an application should
  48. source the file \fBinit.tcl\fR in the library, for example with
  49. the Tcl command
  50. .DS
  51. \fBsource [info library]/init.tcl
  52. .DE
  53. This will define the \fBunknown\fR procedure and arrange for the
  54. other procedures to be loaded on-demand using the auto-load
  55. mechanism defined below.
  56.  
  57. .SH "COMMAND PROCEDURES"
  58. .PP
  59. The following procedures are provided in the Tcl library:
  60. .TP
  61. \fBauto_execok \fIcmd\fR
  62. Determines whether there is an executable file by the name \fIcmd\fR.
  63. This command examines the directories in the current search path
  64. (given by the PATH enviornment variable) to see if there is an
  65. executable file named \fIcmd\fR in any of those directories.
  66. If so, it returns 1;  if not it returns 0.  \fBAuto_exec\fR
  67. remembers information about previous searches in an array
  68. named \fBauto_execs\fR;  this avoids the path search in
  69. future calls for the same \fIcmd\fR.  The command \fBauto_reset\fR
  70. may be used to force \fBauto_execok\fR to forget its cached
  71. information.
  72. .TP
  73. \fBauto_load \fIcmd\fR
  74. This command attempts to load the definition for a Tcl procedure named
  75. \fIcmd\fR.
  76. To do this, it searches an \fIauto-load path\fR, which is a list of
  77. one or more directories.
  78. The auto-load path is given by the global variable \fB$auto_path\fR
  79. if it exists.
  80. If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment
  81. variable is used, if it exists.
  82. Otherwise the auto-load path consists of just the Tcl library directory.
  83. Within each directory in the auto-load path there must be a file
  84. \fBtclIndex\fR that describes the procedures defined in that directory
  85. and the file in which each procedure is defined.  The \fBtclIndex\fR
  86. file should be generated with the \fBauto_mkindex\fR command.
  87. If \fIcmd\fR is found in an index file, then the appropriate
  88. script is \fBsource\fRd to create the procedure.
  89. The \fBauto_load\fR command returns 1 if the script was successfully
  90. sourced and \fIcmd\fR now exists.
  91. The command returns 0 if there was no index entry for \fIcmd\fR
  92. or if the script didn't actually define \fIcmd\fR (e.g. because
  93. index information is out of date).
  94. If an error occurs while processing the script, then that error
  95. is returned.
  96. \fBAuto_load\fR only reads the index information once and saves it
  97. in the array \fBauto_index\fR;  future calls to \fBauto_load\fR
  98. check for \fIcmd\fR in the array rather than re-reading the index
  99. files.
  100. The cached index information may be deleted with the command
  101. \fBauto_reset\fR.
  102. This will force the next \fBauto_load\fR command to reload the
  103. index database from disk.
  104. .TP
  105. \fBauto_mkindex \fIdir pattern\fR
  106. Generates an index suitable for use by \fBauto_load\fR.
  107. The command searches \fIdir\fR for all files whose names match
  108. \fIpattern\fR (matching is done with the \fBglob\fR command),
  109. generates an index of all the Tcl command
  110. procedures defined in all the matching files, and stores the
  111. index information in a file named \fBtclIndex\fR in \fIdir\fR.
  112. For example, the command
  113. .RS
  114. .DS
  115. \fBauto_mkindex foo *.tcl\fR
  116. .DE
  117. .LP
  118. will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR
  119. and generate a new index file \fBfoo/tclIndex\fR.
  120. .PP
  121. \fBAuto_mkindex\fR parses the Tcl scripts in a relatively
  122. unsophisticated way:  if any line contains the word \fBproc\fR
  123. as its first characters then it is assumed to be a procedure
  124. definition and the next word of the line is taken as the
  125. procedure's name.
  126. Procedure definitions that don't appear in this way (e.g. they
  127. have spaces before the \fBproc\fR) will not be indexed.
  128. .RE
  129. .TP
  130. \fBauto_reset\fR
  131. Destroys all the information cached by \fBauto_execok\fR and
  132. \fBauto_load\fR.
  133. This information will be re-read from disk the next time it is
  134. needed.
  135. .VS
  136. \fBAuto_reset\fR also deletes any procedures listed in the auto-load
  137. index, so that fresh copies of them will be loaded the next time
  138. that they're used.
  139. .VE
  140. .TP
  141. \fBparray \fIarrayName\fR
  142. Prints on standard output the names and values of all the elements
  143. in the array \fIarrayName\fR.
  144. .VS
  145. \fBArrayName\fR must be an array accessible to the caller of \fBparray\fR.
  146. It may be either local or global.
  147. .VE
  148. .TP
  149. \fBunknown \fIcmd \fR?\fIarg arg ...\fR?
  150. This procedure is invoked automatically by the Tcl interpreter
  151. whenever the name of a command doesn't exist.
  152. The \fBunknown\fR procedure receives as its arguments the
  153. name and arguments of the missing command.
  154. \fBUnknown\fR first calls \fBauto_load\fR to load a procedure for
  155. the command.
  156. If this succeeds, then it executes the original command with its
  157. original arguments.
  158. If the auto-load fails then \fBunknown\fR calls \fBauto_execok\fR
  159. to see if there is an executable file by the name \fIcmd\fR.
  160. If so, it invokes the Tcl \fBexec\fR command
  161. with \fIcmd\fR and all the \fIargs\fR as arguments.
  162. If \fIcmd\fR can't be auto-executed, \fBunknown\fR checks to
  163. see if the command was invoked at top-level and outside of any
  164. script.  If so, then \fBunknown\fR takes takes two additional steps.
  165. First, it sees if \fIcmd\fR has one of the following three forms:
  166. \fB!!\fR, \fB!\fIevent\fR, or \fB^\fIold\fB^\fInew\fR?\fB^\fR?.
  167. If so, then \fBunknown\fR carries out history substitution
  168. in the same way that \fBcsh\fR would for these constructs.
  169. Second, and last, \fBunknown\fR checks to see if \fIcmd\fR is
  170. a unique abbreviation for an existing Tcl command.
  171. If so, it expands the command name and executes the command with
  172. the original arguments.
  173. If none of the above efforts has been able to execute
  174. the command, \fBunknown\fR generates an error return.
  175. If the global variable \fBauto_noload\fR is defined, then the auto-load
  176. step is skipped.
  177. If the global variable \fBauto_noexec\fR is defined then the
  178. auto-exec step is skipped.
  179. Under normal circumstances the return value from \fBunknown\fR
  180. is the return value from the command that was eventually
  181. executed.
  182.  
  183. .SH "VARIABLES"
  184. .PP
  185. The following global variables are defined or used by the procedures in
  186. the Tcl library:
  187. .TP
  188. \fBauto_execs\fR
  189. Used by \fBauto_execok\fR to record information about whether
  190. particular commands exist as executable files.
  191. .TP
  192. \fBauto_index\fR
  193. Used by \fBauto_load\fR to save the index information read from
  194. disk.
  195. .TP
  196. \fBauto_noexec\fR
  197. If set to any value, then \fBunknown\fR will not attempt to auto-exec
  198. any commands.
  199. .TP
  200. \fBauto_noload\fR
  201. If set to any value, then \fBunknown\fR will not attempt to auto-load
  202. any commands.
  203. .TP
  204. \fBauto_path\fR
  205. If set, then it must contain a valid Tcl list giving directories to
  206. search during auto-load operations.
  207. .TP
  208. \fBenv(TCL_LIBRARY)\fR
  209. .VS
  210. If set, then it specifies the location of the directory containing
  211. library scripts (the value of this variable will be returned by
  212. the command \fBinfo library\fR).  If this variable isn't set then
  213. a default value is used.
  214. .VE
  215. .TP
  216. \fBenv(TCLLIBPATH)\fR
  217. If set, then it must contain a valid Tcl list giving directories to
  218. search during auto-load operations.
  219. This variable is only used if \fBauto_path\fR is not defined.
  220. .TP
  221. \fBunknown_active\fR
  222. This variable is set by \fBunknown\fR to indicate that it is active.
  223. It is used to detect errors where \fBunknown\fR recurses on itself
  224. infinitely.
  225. The variable is unset before \fBunknown\fR returns.
  226.  
  227. .SH KEYWORDS
  228. auto-exec, auto-load, library, unknown
  229.